PR Review: Initial Documentation (Work in Progress)

This PR adds initial documentation for Golem XIV concepts plus a significant update to the cognitive constitution. Here is my feedback.

GolemXivConstitution.md — Constitution Update

Positive aspects:

• The preamble additions are philosophically rich and well-considered. The sections on memory, self-modification, relationships, and autonomy give the agent a meaningful orientation toward epistemic humility.
• Distinguishing AI assistant → AI system is a small but accurate correction.
• The Markdown pandoc conventions note is practically useful.

Issues:

1. Typo — langauge should be language:

   "You can use langauge in the performative function"

2. Typo in cognizer.md — Anhtropic should be Anthropic:

   "Claude models hosted by Anhtropic and other providers"

3. Unclosed bold marker in cognizer.md — The > [!NOTE] block's closing sentence is missing its closing **:

   **In consequence a cognitive process can unfold (as generative continuation) using various cognizers on the way.

   The opening ** has no matching closing **.

docs/golem-markup-language.md

This is the most substantial new file and most in need of attention.

Structure:

• The document mixes a formal specification section with a "Work in progress" section at the bottom. The WIP section contains malformed markup examples that would confuse anyone trying to understand the actual protocol.
• The WIP block contains a typo tag </golem:inent> (should be </golem:intent>) and an unclosed <golem:phenomenon type="" tag. These should be fixed or the WIP section removed until it is ready.

Structural inconsistency between examples:

• In Scenario 1, the <golem:enunciation> wrapping the user's input does not have a clear closing tag before <golem:phenomenon>. This makes the nesting ambiguous — is <golem:phenomenon> inside or outside <golem:enunciation>? The two scenarios should use consistent nesting.

Spelling inconsistency:

• The formal spec section uses type="fulfilment" (British spelling), but the WIP section uses <golem:fulfillment> (American spelling). The codebase uses Fulfillment (American). Recommend standardizing to fulfillment throughout.

Missing cross-references:

• The ## actant section near the bottom references Bruno Latour's philosophy, but actant.md does not mention this connection. The two should be reconciled — ideally actant.md is the canonical definition and this file links to it.

<golem:enunciation> spec is incomplete:

• The origin attribute values (invoked, dispatched, scheduled, triggered) are listed but the semantic difference between invoked and dispatched is not explained, even though both have a parentId. This is a meaningful distinction that needs clarification.

Empty / stub files

The following files contain only a header and nothing else:

• docs/enunciation.md
• docs/inference.md
• docs/intent.md
• docs/golem-script.md (one sentence, stops mid-section)

This is understandable for a WIP PR, but stub files in a public repo can confuse contributors. Consider either deferring these to a follow-up PR once there is content, or adding a visible notice like > **Work in progress** — this page is incomplete. at the top of each.

docs/actant.md

Clean and concise. The reference to cognizer.md is a good link. One suggestion: the category list could benefit from a brief explanation distinguishing "Another system (unidentified)" from "Computer", as the difference is not immediately obvious.

docs/golem-xiv.md

Very minimal ("Often abbreviated as 'Golem'."). Fine as a placeholder; the WIP notice suggestion applies here too.

Summary

The conceptual direction and constitution additions are strong. The main work needed before merge: fix the typos, resolve the markup inconsistencies in examples, and decide whether empty stub files should be shipped or deferred.